Skip to content

[DOC] Document search API #5521

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 17 commits into from
Oct 23, 2025
Merged

[DOC] Document search API #5521

merged 17 commits into from
Oct 23, 2025
+4,859 −1

Conversation

@Sicheng-Pan
Copy link
Contributor

@Sicheng-Pan Sicheng-Pan commented Sep 25, 2025 •
edited
Loading

Description of changes

Summarize the changes made by this PR.

  • Improvements & Bug fixes
    • N/A
  • New functionality
    • Adds search api documentation under chroma cloud section

Test plan

How are these changes tested?

  • Tests pass locally with pytest for python, yarn test for js, cargo test for rust

Migration plan

Are there any migrations, or any forwards/backwards compatibility changes needed in order to make sure this change deploys reliably?

Observability plan

What is the plan to instrument and monitor this change?

Documentation Changes

Are all docstrings for user-facing APIs updated if required? Do we need to make documentation changes in the _docs section?_

@github-actions
Copy link

Reviewer Checklist

Please leverage this checklist to ensure your code review is thorough before approving

Testing, Bugs, Errors, Logs, Documentation

  • Can you think of any use case in which the code does not behave as intended? Have they been tested?
  • Can you think of any inputs or external events that could break the code? Is user input validated and safe? Have they been tested?
  • If appropriate, are there adequate property based tests?
  • If appropriate, are there adequate unit tests?
  • Should any logging, debugging, tracing information be added or removed?
  • Are error messages user-friendly?
  • Have all documentation changes needed been made?
  • Have all non-obvious changes been commented?

System Compatibility

  • Are there any potential impacts on other parts of the system or backward compatibility?
  • Does this change intersect with any items on our roadmap, and if so, is there a plan for fitting them together?

Quality

  • Is this code of a unexpectedly high quality (Readability, Modularity, Intuitiveness)

@Sicheng-Pan Sicheng-Pan force-pushed the sicheng/search-doc branch 2 times, most recently from 42b935d to f3f86db Compare October 10, 2025 18:31
@blacksmith-sh blacksmith-sh bot deleted a comment from Sicheng-Pan Oct 10, 2025
@Sicheng-Pan Sicheng-Pan marked this pull request as ready for review October 13, 2025 21:17
@propel-code-bot
Copy link
Contributor

propel-code-bot bot commented Oct 13, 2025 •
edited
Loading

Add Comprehensive Documentation for Cloud Search API

This PR introduces extensive documentation for the new Search API within the Chroma Cloud section. The changes add a full set of docs pages covering the API's overview, filtering, ranking, hybrid search (RRF), limit/selection, batch operations, migration strategies, practical examples, as well as a sidebar reorganization to include a dedicated Search API group. Existing documentation is also updated with references and contextual callouts to guide users to the new Search API where relevant.

Key Changes

• Added new documentation pages under docs/docs.trychroma.com/markdoc/content/cloud/search-api/ covering: overview, search-basics, filtering, ranking, hybrid-search, pagination-selection, batch-operations, examples, and migration
• Significantly expanded content (nearly 5,000 LOC added) including detailed usage instructions, code samples for Python and TypeScript, technical explanations, best practices, and comprehensive edge-case handling for all Search API functionality
• Updated sidebar-config.ts to add a 'Search API' section with logical grouping and navigation, and reorganized the docs sidebar accordingly
• Minor contextual adjustments in other documentation files (e.g., getting-started.md, query-and-get.md) to reference the new Search API and steer cloud users to the advanced documentation
• Provided migration guidance for moving from legacy query/get APIs to the new search() API, detailing parameter mapping, field selection equivalence, and batch operation migration
• Introduced notes, banners, and inline technical warnings to highlight limitations, best practices, and correct interpretation (e.g., RRF scores are negative and lower is better)
• Added and updated numerous code examples and tabbed blocks for both Python and TypeScript across all new documentation pages

Affected Areas

• docs/docs.trychroma.com/markdoc/content/cloud/search-api/ (new directory and all nested files)
• docs/docs.trychroma.com/markdoc/content/sidebar-config.ts (sidebar update for new nav section)
• docs/docs.trychroma.com/markdoc/content/cloud/getting-started.md
• docs/docs.trychroma.com/markdoc/content/docs/querying-collections/query-and-get.md

This summary was automatically generated by @propel-code-bot

@chroma-core chroma-core deleted a comment from propel-code-bot bot Oct 13, 2025
@chroma-core chroma-core deleted a comment from propel-code-bot bot Oct 13, 2025
@blacksmith-sh blacksmith-sh bot deleted a comment from Sicheng-Pan Oct 13, 2025
itaismith
itaismith requested changes Oct 21, 2025
View reviewed changes
Copy link
Contributor

@itaismith itaismith left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some of the TS examples use type any mostly for collections. We have the Collection type that can be used

philipithomas
philipithomas approved these changes Oct 22, 2025
View reviewed changes
Copy link
Member

@philipithomas philipithomas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM - pushed some changes. Recommend addressing @itaismith's feedback before merging.

@Sicheng-Pan Sicheng-Pan merged commit 7ebd06f into main Oct 23, 2025
61 checks passed
@Sicheng-Pan Sicheng-Pan deleted the sicheng/search-doc branch October 23, 2025 22:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@propel-code-bot propel-code-bot[bot] propel-code-bot[bot] left review comments

@philipithomas philipithomas philipithomas approved these changes

@itaismith itaismith itaismith approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@Sicheng-Pan @philipithomas @itaismith